home *** CD-ROM | disk | FTP | other *** search
/ Amiga Games: Greatest Hits 1996 / Amiga Games: Greatest Hits 1996.iso / archive / userbox / publicdomain / installproged.lha / installproged / sources / DevManual_ITA < prev   
Text File  |  1996-06-03  |  15KB  |  488 lines
  1.  
  2.               -----------------------------------------------
  3.  
  4.                 ProgED V2.1 by Giovanni Lambiase (C) 1995-96
  5.  
  6.                          Note per i programmatori
  7.  
  8.               -----------------------------------------------
  9.  
  10.  
  11. -------------------------
  12.  1. Strutture principali
  13. -------------------------
  14.  
  15.     Per una breve spiegazione sulle varie strutture e relativi campi
  16. vedi il file PED.h.
  17.  
  18.  
  19.  
  20. ------------
  21.  2. Scanner
  22. ------------
  23.  
  24.     Uno scanner deve essere scritto tramite una funzione assembler o una
  25. funzione C che prende gli argomenti nei registri. Il codice risultante
  26. deve essere linkato SENZA alcun modulo di startup, in modo tale che la
  27. prima locazione eseguibile sia l'inizio della funzione scritta. La
  28. funzione di ricerca riceve due argomenti nei seguenti registri:
  29.  
  30.     A0: Indirizzo della linea su cui effettuare la ricerca. Punta ad una
  31.         stringa terminata con 0.
  32.  
  33.     A1: Indirizzo del buffer che conterrà il riferimento, se trovato.
  34.  
  35.     La funzione deve ritornare nel registro D0 la lunghezza della stringa
  36. creata nel buffer puntato da A1. Nel caso la funzione non abbia trovato
  37. nulla deve ritornare 0.
  38.  
  39.     NOTA: è necessario salvare tutti i registri all'ingresso della
  40.           funzione e ripristarli all'uscita.
  41.  
  42.  
  43.  
  44. -----------
  45.  3. Folder
  46. -----------
  47.  
  48.     Una funzione di ricerca dei fold deve essere scritta tramite una funzione
  49. assembler o una funzione C che prende gli argomenti nei registri. Il codice
  50. risultante deve essere linkato SENZA alcun modulo di startup, in modo tale
  51. che la prima locazione eseguibile sia l'inizio della funzione scritta. La
  52. funzione di ricerca riceve due argomenti nei seguenti registri:
  53.  
  54.     A0: è l'indirizzo della struttura PEDWindow relativa al testo su
  55.         cui effettuare la ricerca.
  56.  
  57.     D0: Contiene il numero della colonna su cui è posizionato il cursore.
  58.         (0=prima colonna).
  59.  
  60.     D1: Contiene il numero della linea su cui è posizionato il cursore.
  61.         Tale numero è assoluto. Ciò significa che non tiene conto dei
  62.         fold eventualmente presenti nel testo. (0=prima linea).
  63.  
  64.     A1: Contiene l'indirizzo di una long-word. In tale long-word la funzione
  65.         deve scrivere il numero della linea iniziale del fold, se trovato.
  66.         Anche in questo caso la funzione non deve considerare eventuali
  67.         fold già presenti nel testo. (0=prima linea).
  68.  
  69.     A2: Contiene l'indirizzo di una long-word. In tale long-word la funzione
  70.         deve scrivere il numero della linea finale del fold, se trovato.
  71.         Anche in questo caso la funzione non deve considerare eventuali
  72.         fold già presenti nel testo. (0=prima linea).
  73.  
  74.     A3: Punta ad un buffer in cui la funzione deve scrivere la stringa
  75.         che ProgED scriverà a fianco dell'indicatore ">FOLD". Generalmente
  76.         il nome della funzione C, ecc.
  77.  
  78.     La funzione deve ritornare in D0 il valore 1 se ha trovato un fold, 0
  79. altrimenti. Nel primo caso la funzione deve anche fornire, tramite A1 e A2
  80. i numeri di linea iniziali e finali del fold e, tramite A3, la stringa
  81. rappresentante il fold. è necessario,infine, salvare tutti i registri
  82. all'ingresso della funzione e ripristinarli all'uscita.
  83.  
  84.     NOTA: la funzione 'FOLD ALL' viene eseguita eseguendo una chiamata
  85. alla funzione su tutte le linee (dalla prima all'ultima) e con il
  86. numero di colonna pari a 0 (prima colonna).
  87.  
  88.  
  89.  
  90. ----------------
  91.  4. Clienti API
  92. ----------------
  93.  
  94.     ProgED consente ad applicazioni esterne (chiamate "clienti") di
  95.  "agganciarsi" ad esso. Un cliente API è semplicemente un normale
  96. programma (scritto in qualsiasi linguaggio). Tale programma deve
  97. essere scritto in modo tale da "registrarsi" presso il ProgED. Ciò
  98. consente al ProgED di tracciare tutti i clienti e di mandar loro
  99. messaggi sulle operazioni che devono effettuare.
  100.  
  101. I messaggi che un cliente deve inviare a ProgED (nella sua porta
  102. API di nome "PED_API") hannno la seguente struttura:
  103.  
  104.  
  105.  
  106.     struct APIMessage
  107.     {
  108.         struct Message     am_Message;
  109.         ULONG              am_MsgType,
  110.                            am_MsgArg[10],
  111.                            am_RC;
  112.     }
  113.  
  114.     am_Message:
  115.  
  116.          è un campo contenente un messaggio standard Exec.
  117.  
  118.     am_MsgType:
  119.  
  120.          Contiene il tipo di messaggio da inviare.
  121.  
  122.     am_MsgArg[]:
  123.  
  124.          è un vettore contenente un massimo di 10 argomenti
  125.          dipendenti dal tipo del messaggio
  126.  
  127.     am_RC:
  128.  
  129.          è il codice di ritorno che ProgED restituisce al cliente
  130.          per informarlo sul successo dell'operazione.
  131.  
  132.  
  133.  
  134.  
  135.     I tipi di messaggi che un cliente può spedire a ProgED sono, per ora:
  136.  
  137.     PED_API_REGISTER:
  138.  
  139.           Registra un cliente presso ProgED. Richiede un puntatore ad una
  140.           struttura di tipo APIClient in am_MsgArg[0]. Non ritorna nessun
  141.           risultato in am_RC.
  142.  
  143.     PED_API_UNREGISTER:
  144.  
  145.           Informa ProgED che il cliente vuole andarsene (!?). Richiede lo
  146.           STESSO puntatore dato al momento della registrazione, con il
  147.           messaggio PED_API_REGISTER, in am_MsgArg[0]. Non ritorna nessun
  148.           risultato in am_RC.
  149.  
  150.     PED_API_ADD_INTERNAL_COMMAND:
  151.  
  152.           Consente di espandere le funzionalità del ProgED aggiungendo un
  153.           nuovo comando interno. A tale scopo è necessario allocare e
  154.           riempire una struttura ArexxExtCmds e fornire il suo puntatore
  155.           in am_MsgArg[0]. Nessun risultato in am_RC.
  156.  
  157.     PED_API_REM_INTERNAL_COMMAND:
  158.  
  159.           Rimuove un comando precedentemente aggiunto tramite il messaggio
  160.           PED_API_ADD_INTERNAL_COMMAND. è necessario fornire in am_MsgArg[0]
  161.           lo STESSO puntatore dato al momento dell'aggiunta del comando.
  162.           Non ritorna risultati in am_RC.
  163.  
  164.     PED_API_GET_ACTIVE_WINDOW:
  165.  
  166.         Ottiene, in am_RC, l'indirizzo della struttura PEDWindow associata
  167.         alla finestra attualmente attiva.
  168.  
  169.     PED_API_GET_WINDOW_LIST:
  170.  
  171.         Ottiene, in am_RC, l'indirizzo iniziale della lista di strutture
  172.         PEDWindow corrispondenti ai testi in memoria.
  173.  
  174.     PED_GET_SCREEN_ADDRESS:
  175.  
  176.         Ottiene, in am_RC, l'indirizzo dello schermo del ProgED. Se il ProgED
  177.         è attualmente iconificato ritorna NULL.
  178.  
  179.     PED_GET_PREFS_ADDRESS:
  180.  
  181.         Ottiene, in am_RC, l'indirizzo della struttura Prefs.
  182.  
  183.     PED_GET_PUBSCRNAME:
  184.  
  185.         Ottiene, in am_RC, un puntatore al nome dello schermo pubblico
  186.         aperto dal ProgED.
  187.  
  188.     NOTA: La struttura ArexxExtCmds (e tutti gli oggetti a cui puntano i
  189.           suoi campi), fornita al momento dell'aggiunta del comando, deve
  190.           rimanere valida in memoria. è possibile riutilizzarla (o
  191.           liberare la memoria associata solo DOPO aver utilizzato un
  192.           messaggio di tipo PED_REM_INTERNAL_COMMAND.
  193.           Lo stesso vale per la struttura APIClient utilizzata per il
  194.           messaggio PED_API_ADD_INTERNAL_COMMAND. In questo caso è
  195.           possibile riutilizzare la struttura dopo il corrispondente
  196.           messaggio PED_API_REM_INTERNAL_COMMAND.
  197.  
  198.  
  199.  
  200.  
  201.     I messaggi che ProgED può inviare ad un cliente sono, per ora:
  202.  
  203.     PED_API_SHOW:
  204.  
  205.         ProgED ha riaperto il suo schermo. L'indirizzo dello schermo
  206.         può essere ottenuto nel campo am_MsgArg[0]. Nel campo am_MsgArg[1],
  207.         invece, si trova un puntatore al nome dello schermo pubblico
  208.         utilizzato. Il cliente puo' utilizzare queste due informazioni
  209.         per aprire eventuali finestre sullo schermo del ProgED. Questo
  210.         messaggio viene spedito solo se, al momento della registrazione,
  211.         il cliente ha settato il flag NOTIFY_ON_SHOWHIDE.
  212.  
  213.     PED_API_HIDE:
  214.  
  215.         ProgED stà per chiudere il suo schermo. Questo messaggio viene
  216.         spedito solo se, al momento della registrazione, il cliente ha
  217.         settato il flag NOTIFY_ON_SHOWHIDE.
  218.  
  219.  
  220.     PED_API_KEY:
  221.  
  222.         L'utente ha battuto un tasto. Il cliente può ottenere la struttura
  223.         IntuiMessage relativa leggendo il campo am_MsgArg[0]. Tale campo
  224.         conterrà il puntatore alla struttura IntuiMessage contenente il
  225.         messaggio di tipo RAWKEY ricevuto dal ProgED. Nel campo am_MsgArg[1],
  226.     invece, il cliente può leggere l'indirizzo della struttura
  227.         PEDWindow associata alla finestra che ha ricevuto il messaggio.
  228.     Questo messaggio viene spedito solo se, al momento della registrazione,
  229.         il cliente ha settato il flag NOTIFY_ON_KEY.
  230.  
  231.         NOTA: In ogni caso, al termine della gestione di questo messaggio,
  232.         ProgED eseguirà l'azione legata al tasto. Inoltre il cliente
  233.         NON DEVE modificare il messaggio stesso, perchè è un messaggio
  234.         proveniente da Intuition!
  235.  
  236.     PED_API_QUIT:
  237.  
  238.         ProgED sta per terminare. Alla ricezione di questo messaggio (che
  239.         viene SEMPRE inviato a prescindere dai flag NOTIFY_xxx) il cliente
  240.         deve chiudere le eventuali finestre e terminare. E' VIETATO
  241.         UTILIZZARE LA PORTA API DOPO LA RICEZIONE DI QUESTO MESSAGGIO !!!!!
  242.         Questo implica che, dopo la ricezione di questo messaggio, il
  243.         cliente NON DEVE tentare di togliere la registrazione e/o la
  244.         definizione di comandi esterni.
  245.  
  246.  
  247.  
  248.     Qui di seguito sono riportate le spiegazioni riguardanti i campi delle
  249. diverse strutture utilizzate.
  250.  
  251.  
  252.     struct APIClient
  253.     {
  254.         struct MsgPort          *ac_ClientPort;
  255.         ULONG                    ac_Notify;
  256.         char                    *ac_name;
  257.         struct APIClient        *ac_Next;
  258.     }
  259.  
  260.     ac_ClientPort:
  261.  
  262.         Indica l'indirizzo di una porta messaggi a cui ProgED invierà i
  263.         messaggi informativi al cliente. Questo tipo di messaggi verrà
  264.         spiegato successivamente.
  265.  
  266.     ac_Notify:
  267.  
  268.         Indica quali tipi di messaggi il cliente vuole ricevere dal ProgED.
  269.         Gli unici tipi di messaggi selezionabili attualmente sono indicati
  270.         dal flag NOTIFY_ON_SHOW_HIDE. 
  271.  
  272.     ac_Name:
  273.  
  274.         Punta al nome del cliente.
  275.  
  276.     ac_Next:
  277.  
  278.         Porre a NULL. Conterrà il successore cliente della lista interna
  279.         del ProgED.
  280.  
  281.  
  282.  
  283.  
  284.     struct ArexxExtCmds
  285.     {
  286.         UBYTE                    External;
  287.         char                    *Name;
  288.         char                    *Template;
  289.         void                    *Defaults[MAXREXXARGS];
  290.         LONG ASM                (*CommFunc)( RG(a0) struct CommandData *);
  291.         struct ArexxExtCmds     *NextCmd;
  292.     }
  293.  
  294.     External:
  295.  
  296.         Indica che il comando è gestito da un cliente. Porre SEMPRE a TRUE.
  297.  
  298.     Name:
  299.  
  300.         Nome del comando. Specificare sempre in lettere maiuscole.
  301.  
  302.     Template:
  303.  
  304.         è il template AmigaDOS del comando.
  305.  
  306.     Default[]:
  307.  
  308.         Indica il vettore di puntatori che deve essere passato alla
  309.         funzione ReadArgs della dos.library. Deve contenere i valori
  310.         di default dei parametri del template. Per ulteriori informazioni
  311.         leggere la documentazione della funzione ReadArgs.
  312.  
  313.     CommFunc:
  314.  
  315.         Indica il puntatore alla funzione che realizza il comando. Tale
  316.         funzione deve essere scritta in assembler (o ricevere i parametri
  317.         come una funzione assembler). Essa deve ricevere un puntatore ad
  318.         una struttura CommandData in A0 e ritornare il codice d'errore
  319.         risultante dall'esecuzione in D0. In seguito analizzeremo la
  320.         struttura CommandData.
  321.  
  322.     NextCmd:
  323.  
  324.         Porre a NULL. ProgED ne modificherà il valore portandolo a
  325.         puntare al prossimo comando fornito dallo stesso cliente o da
  326.         un altro.
  327.  
  328.  
  329.  
  330.  
  331.     struct CommandData
  332.     {
  333.         char              *CommandLine;
  334.         void             **CommandArgs;
  335.         struct MyWindow   *CurrentWindow,
  336.                           *FirstWindow;
  337.         struct Prefs      *CurrentPrefs;
  338.         LONG ASM (*ExecuteInternalCommand)(RG(a0) char *);
  339.     }
  340.  
  341.     CommandLine:
  342.  
  343.         Punta ad una stringa riportante l'intera linea di comando riguardante
  344.         il comando.
  345.  
  346.     CommandArgs:
  347.  
  348.         Punta ad un vettore di (void *). Ogni puntatore deve essere utilizzato
  349.         secondo le norme dettate dalla ReadArgs. Questo vettore, infatti, è
  350.         il risultato della applicazione della stessa funzione alla linea di
  351.         comando (tenendo presente i default dati nella struttura ArexxExtCmds).
  352.  
  353.     CurrentWindow:
  354.  
  355.         Indica il puntatore alla struttura PEDWindow indicante la finestra
  356.         attualmente attiva.
  357.  
  358.     FirstWindow:
  359.  
  360.         Indica il puntatore alla prima struttura PEDWindow della lista di
  361.         finestre mantenuta dal ProgED.
  362.  
  363.     CurrentPrefs:
  364.  
  365.     Punta ad una struttura Prefs contenente le preferenze attuali.
  366.  
  367.     ExecuteInternalCommand:
  368.  
  369.         è un puntatore ad una funzione assembler. Chiamando questa
  370.         funzione (specificando in A0 il puntatore ad una stringa) è
  371.         possibile eseguire i comandi interni del ProgED. A tale scopo
  372.         la stringa puntata da A0 deve contenere la linea di comando
  373.         desiderata. In D0 viene ritornato il codice d'errore risultante.
  374.  
  375.         NOTA: Non utilizzare la porta ARexx di ProgED per eseguire i
  376.         comandi interni! Così facendo, infatti, si bloccherebbero
  377.         sia ProgED che il cliente. Ciò è dovuto al fatto che, mentre
  378.         ProgED esegue la funzione che implementa il comando, NON PUò
  379.         rispondere ai messaggi provenienti da sè stesso!
  380.  
  381.  
  382.  
  383. -------------------
  384.  5. Funzioni utili
  385. -------------------
  386.  
  387.     Le funzioni C che seguono sono utili per la scrittura di folder e
  388. scanner. Esse riguardano la ricerca di linee. Potete utilizzarle
  389. tagliandole da questo testo e inserendole nei vostri programmi.
  390.  
  391.  
  392.  
  393. /*****
  394.  *
  395.  * FUNZIONE:    struct Line *SearchLine(struct Line *line,int y)
  396.  *
  397.  * SCOPO:    Cerca l'indirizzo della linea "y-esima" (0=prima) a partire
  398.  *        dalla prima linea del file data da line.
  399.  *        NB: Tiene conto dei FOLDS.
  400.  *
  401.  * RESTITUISCE: Un puntatore alla linea cercata.
  402.  *
  403.  ****/
  404.  
  405. struct Line *SearchLine(struct Line *line,int y)
  406. {
  407.     while(((y--)>0)&&(line))    line=NextLine(line);
  408.     return(line);
  409. }
  410.  
  411.  
  412.  
  413. /*****
  414.  *
  415.  * FUNZIONE:    int SearchLine2(struct Line *line,int y)
  416.  *
  417.  * SCOPO:    Cerca il # della linea (tenendo conto dei FOLD)
  418.  *        della linea ASSOLUTA y.
  419.  *
  420.  * RESTITUISCE: Il # della linea cercata.
  421.  *
  422.  ****/
  423.  
  424. int SearchLine2(struct Line *line,int y)
  425. {
  426.     int    n=0;
  427.  
  428.     while(((y--)>0)&&(line))
  429.     {
  430.         if (!line->Folder)    n++;
  431.         else    if (line->NextLine)
  432.                 if (!line->NextLine->Folder)    n++;
  433.         line=line->NextLine;
  434.     }
  435.     if (line)    return(n);
  436.     else        return(0);
  437. }
  438.  
  439.  
  440.  
  441. /*****
  442.  *
  443.  * FUNZIONE:    int SearchLine3(struct Line *first,struct Line *line)
  444.  *
  445.  * SCOPO:    Cerca il # assoluto della linea line a partire
  446.  *        dalla prima linea del file data da first.
  447.  *        NB: NON tiene conto dei FOLDS.
  448.  *
  449.  * RESTITUISCE: Il # della linea cercata.
  450.  *
  451.  ****/
  452.  
  453. int SearchLine3(struct Line *first,struct Line *line)
  454. {
  455.     long    n=0;
  456.  
  457.     while(first)
  458.     {
  459.         if (first==line)    break;
  460.         n++;
  461.         first=first->NextLine;
  462.     }
  463.     return(n);
  464. }
  465.  
  466.  
  467.  
  468. /*****
  469.  *
  470.  * FUNZIONE:    struct Line *SearchLine4(struct Line *line,int y)
  471.  *
  472.  * SCOPO:    Cerca l'indirizzo della linea "y-esima" (0=prima) a partire
  473.  *        dalla prima linea del file data da line.
  474.  *        NB: NON tiene conto dei FOLDS.
  475.  *
  476.  * RESTITUISCE: Un puntatore alla linea cercata.
  477.  *
  478.  ****/
  479.  
  480. struct Line *SearchLine4(struct Line *line,int y)
  481. {
  482.     while(((y--)>0)&&(line))    line=line->NextLine;
  483.     return(line);
  484. }
  485.  
  486.  
  487.  
  488.